﻿// -----------------------------------------------------------------------
// <copyright file="AnyNotificationListener.cs" company="Zen Design Corp">
// TODO: Update copyright text.
// </copyright>
// -----------------------------------------------------------------------

namespace Zen.BlackBerry.Acknowledgement
{
	using Zen.BlackBerry.Push;

	/// <summary>
	/// Implementation of the "last" notification listener.
	/// It extends <see cref="T:NotificationListener"/> and sets the
	/// <c>ListenerType</c>to <see cref="T:ListenerType.Last"/>.
	/// Any class that extends this class must provide an implementation
	/// of the Process method. 
	/// </summary>
	public abstract class LastNotificationListener : NotificationListener
	{
		/// <summary>
		/// Gets the type of the listener.
		/// </summary>
		/// <value>The type of the listener.</value>
		public override sealed ListenerType ListenerType
		{
			get
			{
				return ListenerType.Last;
			}
		}

		/// <summary>
		/// Processes the result notification.
		/// </summary>
		/// <param name="pushId">The push-id to which the notification pertains.</param>
		/// <param name="listenerType">
		/// Type of the notification message.
		/// Note: ListenerType.Any will never be passed here
		/// </param>
		/// <param name="pushOutcome">The outcome of pushing to a particular address.</param>
		/// <remarks>
		/// <para>
		/// The client address (eg: PIN) in the result notification from the PPG
		/// was mapped to the address in the provided <see cref="PushOutcome"/>
		/// using the currently known mapping. This may lead in incorrect results
		/// if a subscriber or device swap occurred after the push request was
		/// issued.
		/// </para>
		/// <para>
		/// Note: The <see cref="PushOutcome.Address"/> may return "*" (without quotes)
		/// that indicates that the code applies to all addresses of the push with
		/// the specified push id.
		/// </para>
		/// </remarks>
		public sealed override void Process(string pushId, ListenerType listenerType, PushOutcome pushOutcome)
		{
			Process(pushId, pushOutcome);
		}

		/// <summary>
		/// Processes the result notification.
		/// </summary>
		/// <param name="pushId">The push-id to which the notification pertains.</param>
		/// <param name="pushOutcome">The outcome of pushing to a particular address.</param>
		/// <remarks>
		/// <para>
		/// The client address (eg: PIN) in the result notification from the PPG
		/// was mapped to the address in the provided <see cref="PushOutcome"/>
		/// using the currently known mapping. This may lead in incorrect results
		/// if a subscriber or device swap occurred after the push request was
		/// issued.
		/// </para>
		/// <para>
		/// Note: The <see cref="PushOutcome.Address"/> may return "*" (without quotes)
		/// that indicates that the code applies to all addresses of the push with
		/// the specified push id.
		/// </para>
		/// </remarks>
		public abstract void Process(string pushId, PushOutcome pushOutcome);
	}
}
